Apple Developer Connection 1998 Fall: Game Toolkit/Disc.iso/SDKs/PCI Driver Development Kit/• Tools/Utility/LogLibrary 950622/Src/LogLibrary.h

C/C++ Source or Header | 1996-08-20 | 29.1 KB | 722 lines | [TEXT/MPCC]

/*                                        LogLibrary.h                                */
/*
 * LogLibrary.h
 * Copyright © 1992-95 Apple Computer Inc. All Rights Reserved.
 * Programmed by Martin Minow,
 *    Internet:    [e-mail]
 *    AppleLink:    MINOW
 * Version of May 25, 1995
 */
#ifndef __LogLibrary__
#define __LogLibrary__
/*
 * Usage:
 *    PowerPC (native):
 *        Include "LogLibrary.h" in all compilations.
 *        Either compile the LogLibrary functions or include LogLibrary (shared library).
 *    68000 emulation
 *        Include "LogLibrary.h" in all compilations.
 *        Compile LogLibrary.c, LogConvertTimestamp.c, and LogFormatTimestamp.c
 *        (or include an object).
 *        Make LogLibrary known to the executing program, possibly by storing
 *        it in the Extensions folder.
 *
 * Edit History
 *    94.10.16 MM        Revised (throughly) from the Audit library to take advantage of
 *                    the new I/O architecture. The library name has been changed from
 *                    Audit to DriverLog. The driver log is named through the System
 *                    Name Registry. These functions are (currently) only available in
 *                    PowerPC.
 *    94.12.12 MM        Finished converting to LogLibrary, added Mixed Mode support so
 *                    the (Power PC) library may be called from 68000 code.
 *    95.02.03 MM        • Changed WriteLogEntry, StoreLogEntry, and ReadLogEntry to return
 *                    OSErr's (to distinguish between semaphore interlock and other
 *                    errors). This will allow a non-interrupt application to loop
 *                    while the semaphore is interlocked, though this is not trivial.
 *                    • Removed the StoreString function (now inlined).
 *                    • Removed the lost data counter and entry. Sequence gaps can
 *                    best be determined by watching the atomic sequence counter.
 *                    • Use IncrementAtomic to update the sequence counter. This will
 *                    also count data lost if the semaphore is interlocked.
 *                    • StoreLogEntry stores the sequence counter and timestamp into
 *                    the caller's LogEntryRecord: it is not called with a const
 *                    LogEntryPtr.
 * 95.03.31 MM        Added 68000-callable UpTime, removed UpTime from ReadLogEntry and
 *                    CopyLogRecordEntry. LogConvertTimestamp doesn't need this.
 * 1995.04.07    MM    Some compilers mis-handle functions returning structures. Store
 *                    UpTime returned values in a volatile local variable before using
 *                    them in a function call.
 * 1995.04.11    MM    Ensure that the Code Fragment is loaded into the System Heap.
 * 1995.04.29    MM    Split into LogLibrary (PPC) and LogLibrary68 (68000). This
 *                    was done for the benefit of the MacsBug dcmd. This change
 *                    resulted in a significant simplification of the code as all
 *                    of the cross-architecture code was moved to LogLibrary68.c.
 * 1995.05.25    MM    Some minor cleanups (parameters marked "const"). Removed all
 *                    dependencies on the Name Registry. The underlying Create
 *                    routine uses a SecondaryInterruptHandler to prevent two
 *                    asynchronous tasks from adding the same record.
 *
 * Note: because Pascal does not support variable-length calling sequences, the
 * WriteLogEntry function may only be called from C. Pascal programs must format the
 * LogEntryRecord and call StoreLogEntry directly.
 */
/*
 * To create an log library record, a driver, application, or other code segment calls
 * MakeLogRecord(). This is the only function that accesses the memory manager (but
 * see the note on 68000's below). The record is created by the PoolAllocateResident
 * routine and must be called from task level. If the log has already been created, it
 * returns a pointer to that log record.
 *
 * MakeLogRecord() must be called in a context that can allocate memory. The first
 * call from a 68000 architecture module must be able to load a shared library.
 *
 * To log data, call the WriteLogEntry() routine, normally using one of the formatting
 * macros.
 *
 * To read the next entry from the log, call the ReadLogEntry() routine.
 *
 * Once created, a log persists until system restart. The problem is that many
 * routines might have grabbed the log address from the name registry, so deleting
 * it from the registry is insufficient.
 *
 * There are a few other routines, but they aren't that important.
 *
 * A reader application processes log entries as follows.
 *
 *         Str255                timeText, dataText;
 *        LogRecordPtr        logRecordPtr;
 *        LogEntryPtr            logEntryPtr;
 *        DateTimeRec            eventTime;
 *        UInt32                nanoseconds;
 *
 *        MyOpenLogOutputFile();
 *        logPtr = GetLogRecordPtr("MyLogRecord");
 *        if (logPtr != NULL) {
 *            while (gQuitNow == FALSE) {
 *                ProcessOneEvent();
 *                for (i = 0; i < 10; i++) {
 *                    if (ReadLogEntry(logPtr, &logEntry) != noErr)
 *                        break;
 *                    else {
 *                        ConvertLogEntryTimestamp(&logEntry, &eventTime, &nanoseconds);
 *                        FormatLogEntryTimestamp(timeText, &eventTime, nanoseconds);
 *                        FormatLogEntryData(&logEntry, dataText);
 *                        printf("%.*s: %.*s\n",
 *                            timeText[0], &timeText[1],
 *                            dataText[0], &dataText[1]
 *                        );
 *                    }
 *                }
 *            }
 *        }
 *        ExitToShell();
 */

#ifndef SystemSevenOrLater
#define SystemSevenOrLater    1
#endif

#include <stdarg.h>
#ifndef THINK_C /* Temp until headers stabalize */
#include <MixedMode.h>
#include <Types.h>
#include <OSUtils.h>
#include <DriverServices.h>
#endif

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Public definitions for the LogLibrary.
 *
 * We can store kLogEntryDataSize longwords in each entry. This is the maximum
 * that we can store, given 3 bits per format value.
 */
#define kLogEntryDataSize        10
/*
 * Boolean32 is a Boolean stored in a longword. This prevents Think vs. MPW
 * variable confusion.
 */
typedef UInt32                    Boolean32;
/*
 * Define the LogRecord name.
*/
enum {
    kLogRecordNameBufSize = 32,    /* Includes the terminating NUL    */
    kLogNameTerminator    = '\0'
};
typedef char LogRecordNameByte, *LogRecordNamePtr, LogRecordNameBuf[kLogRecordNameBufSize];

/*
 * Each log record entry contains the following information:
 *        eventTime        The system UpTime value at the time the data was collected.
 *        sequence        The ordinal index of this entry. This will always increment.
 *                        (If you log one entry per microsecond, it will wrap around
 *                        after about 70 minutes).
 *        idCode            A longword that uniquely identifies the log entry (i.e.,
 *                        who logged it). This is provided by the WriteLogEntry caller.
 *        format            A longword that describes the format of the log data.
 *        data[10]        Ten longwords that contain the entry-unique information.
 *                        The actual count is defined by the format longword.
 * upTime and sequence are maintained by LogLibrary routines, while the other
 * parameters are copied from the WriteLogEntry parameters.
 */
#if defined(powerc) || defined(__powerc)
#pragma option align=mac68K
#endif
struct LogEntryRecord {
    AbsoluteTime        eventTime;        /* UpTime() at SaveLogEntry call            */
    UInt32                sequence;        /* Entry number (monotomically increasing)    */
    OSType                idCode;            /* Why are we logging -- set by caller        */
    UInt32                format;            /* Format of the data (see below)            */
    UInt32                data[kLogEntryDataSize];    /* The data itself                */
};
#if defined(powerc) || defined(__powerc)
#pragma options align=reset
#endif
typedef struct LogEntryRecord LogEntryRecord, *LogEntryPtr;
/*
 * These flags control data formatting. Note: because data is passed using
 * variable-length argument list conventions and we want the code to work
 * compatably on both Think and MPW, all numeric parameters must be passed as
 * "long" or "unsigned long." For example, to pass an OSErr code, do
 *        WriteLogEntry(
 *            'fubr',
 *            LogFormat1(kLogFormatSigned),
 *            (signed long) statusCode
 *        );
 */
enum {
    /*
     * Parameters to the LogFormat macro.
     */
    kLogFormatSigned            = 0,        /* Signed long                            */
    kLogFormatUnsigned            = 1,        /* Unsigned (decimal)                    */
    kLogFormatHex                = 2,        /* Unsigned (hex + 'char')                */
    kLogFormatAddress            = 3,        /* Unsigned hex only                    */
    kLogFormatReserved4            = 4,        /* Unused                                */
    kLogFormatReserved5            = 5,        /* Unused                                */
    kLogFormatString            = 6,        /* String (last format)                    */
    kLogFormatEnd                = 7,        /* End signal (no data)                    */
    /*
     * kLogFormatShift must be large enough to shift all format codes. All data
     * format codes must fit into a single longword.
     */
    kLogFormatShift                = 3,
    kLogFormatMask                = (1 << kLogFormatShift) - 1
};
#if ((kLogFormatShift * kLogEntryDataSize) > 32)
    << (kLogFormatShift * kLogEntryDataSize) must be <= 32 bits (longword size) >>
#endif

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * This section should be regarded as "private" to the LogLibrary. Applications
 * that use the library never need to reference (or dereference) these structures.
 * Although the content of the structures is shown explicitly, applications should
 * treat these structures as "opaque" and "subject to change without notice" in
 * future Macintosh operating system releases.
 *
 */
/*
 * The LogRecord iterator contents are private to the library.
 */
#if defined(powerc) || defined(__powerc)
#pragma option align=mac68K
#endif
struct LogRecordIter {
    struct LogRecord    *logRecordPtr;
};
#if defined(powerc) || defined(__powerc)
#pragma options align=reset
#endif
typedef struct LogRecordIter LogRecordIter, *LogRecordIterPtr;

#if defined(powerc) || defined(__powerc)
#pragma option align=mac68K
#endif
struct LogRecord {
    struct LogRecord    *logRecordLink;        /* -> Next LogRecord instance            */
    LogRecordNameBuf    logName;            /* This LogRecord's identification        */
    volatile UInt32        semaphore;            /* In critical section if non-zero        */
    volatile UInt32        lostLockCounter;    /* Can't enter critical section            */
    volatile UInt32        sequenceCounter;    /* Absolute sequence counter            */
    volatile UInt32        flags;                /* Logging & lost data flags            */
    volatile UInt32        entryPutIndex;        /* Where to store the next record        */
    volatile UInt32        entryGetIndex;        /* Where to retrieve the next record    */
    volatile UInt32        entryMaxIndex;        /* Actual number of log entries            */
    LogEntryRecord        entries[1];            /* Log entries are stored here            */
};
#if defined(powerc) || defined(__powerc)
#pragma options align=reset
#endif
typedef struct LogRecord LogRecord, *LogRecordPtr;
/*
 * Values for the flags variable in the LogDataRecord. These are private to the
 * LogData library and dcmd display routine.
 */
enum {
    kLogDataEnabledMask            = (1L <<  0),    /* Enable logging if set            */
    kLogDataPreserveFirstMask    = (1L <<  1),    /* Preserve first entry if set        */
    kLogDataRecordUpTimeMask    = (1L <<  2),    /* Don't record UpTime if set        */
    kLogDataWrapAroundMask        = (1L <<  3)    /* Log has wrapped around once        */
};

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * The following information is public.
 *
 * The LogFormat macro stores the format word.
 */
#define LogFormat(f0, f1, f2, f3, f4, f5, f6, f7, f8, f9)    \
    (  (f0)                                            \
     | ((f1) << (kLogFormatShift * 1))                \
     | ((f2) << (kLogFormatShift * 2))                \
     | ((f3) << (kLogFormatShift * 3))                \
     | ((f4) << (kLogFormatShift * 4))                \
     | ((f5) << (kLogFormatShift * 5))                \
     | ((f6) << (kLogFormatShift * 6))                \
     | ((f7) << (kLogFormatShift * 7))                \
     | ((f8) << (kLogFormatShift * 8))                \
     | ((f9) << (kLogFormatShift * 9))                \
    )
#define LogFormat1(f0)                                                            \
    LogFormat(                                                                    \
        (f0),          kLogFormatEnd, kLogFormatEnd, kLogFormatEnd,                \
        kLogFormatEnd, kLogFormatEnd, kLogFormatEnd, kLogFormatEnd,                \
        kLogFormatEnd, kLogFormatEnd                                            \
    )
#define LogFormat2(f0, f1)                                                        \
    LogFormat(                                                                    \
        (f0),          (f1),          kLogFormatEnd, kLogFormatEnd,                \
        kLogFormatEnd, kLogFormatEnd, kLogFormatEnd, kLogFormatEnd,                \
        kLogFormatEnd, kLogFormatEnd                                            \
    )
#define LogFormat3(f0, f1, f2)                                                    \
    LogFormat(                                                                    \
        (f0),          (f1),          (f2),          kLogFormatEnd,                \
        kLogFormatEnd, kLogFormatEnd, kLogFormatEnd, kLogFormatEnd,                \
        kLogFormatEnd, kLogFormatEnd                                            \
    )
#define LogFormat4(f0, f1, f2, f3)                                                \
    LogFormat(                                                                    \
        (f0),          (f1),          (f2),          (f3),                        \
        kLogFormatEnd, kLogFormatEnd, kLogFormatEnd, kLogFormatEnd,                \
        kLogFormatEnd, kLogFormatEnd                                            \
    )
#define LogFormat5(f0, f1, f2, f3, f4)                                            \
    LogFormat(                                                                    \
        (f0),          (f1),          (f2),          (f3),                        \
        (f4),            kLogFormatEnd, kLogFormatEnd, kLogFormatEnd,            \
        kLogFormatEnd, kLogFormatEnd                                            \
    )
#define LogFormat6(f0, f1, f2, f3, f4, f5)                                        \
    LogFormat(                                                                    \
        (f0),          (f1),          (f2),          (f3),                        \
        (f4),          (f5),          kLogFormatEnd, kLogFormatEnd,                \
        kLogFormatEnd, kLogFormatEnd                                            \
    )
#define LogFormat7(f0, f1, f2, f3, f4, f5, f6)                                    \
    LogFormat(                                                                    \
        (f0),          (f1),          (f2),          (f3),                        \
        (f4),          (f5),          (f6),          kLogFormatEnd,                \
        kLogFormatEnd, kLogFormatEnd                                            \
    )
#define LogFormat8(f0, f1, f2, f3, f4, f5, f6, f7)                                \
    LogFormat(                                                                    \
        (f0),          (f1),          (f2),          (f3),                        \
        (f4),          (f5),          (f6),          (f7),                        \
        kLogFormatEnd, kLogFormatEnd                                            \
    )
#define LogFormat9(f0, f1, f2, f3, f4, f5, f6, f7, f8)                            \
    LogFormat(                                                                    \
        (f0),          (f1),          (f2),          (f3),                        \
        (f4),          (f5),          (f6),          (f7),                        \
        (f8),          kLogFormatEnd                                            \
    )
#define LogFormat10(f0, f1, f2, f3, f4, f5, f6, f7, f8, f9)                        \
    LogFormat(                                                                    \
        (f0),          (f1),          (f2),          (f3),                        \
        (f4),          (f5),          (f6),          (f7),                        \
        (f8),          (f9)                                                        \
    )
/*
 * These are popular format types.
 */
#define LogNoFormat    (LogFormat1(kLogFormatEnd))
#define LogStringFormat    LogFormat1(kLogFormatString)
#define LogStatusFormat    LogFormat2(kLogFormatSigned, kLogFormatString)

/*
 * The application or code segment calls the following functions to access LogRecord
 * records MakeLogRecord must be called from a non-interrupt execution level as it may
 * allocate memory and store information into the System Name Registry. MakeLogRecord
 * or GetLogRecordPtr must be called before calling any other LogRecord function.
 *
 * GetLogRecordPtr can generally be called either from noninterrupt or secondary
 * execution level, however the first call from a 68000 architecture module must be
 * able to load a shared library and, potentially, allocate memory.
 *
 * All other routines may be called from any execution level.
 */

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * LogLibrary68Initialize
 *
 * This function is only called from a 68000 module to "soft-link" to the LogLibrary.
 * It calls the Code Fragment Manager and, implicitly, requires access to the file
 * system and may allocate memory. This function does nothing if called from a
 * PowerPC native module.
 */
pascal OSErr            LogLibrary68Initialize(void);

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * MakeLogRecord
 *
 * The first time this function is called after the system is started, it creates a
 * log record for this name. The log is initially enabled, and deletes overflow at the
 * start. It thus retains the *end* of the log -- this is useful for ongoing logging,
 * but may lose the start of a disaster sequence (as it records the flow of errors
 * through the system, rather than the intial cause.
 *
 * LogRecordNamePtr must define a non-null string. nEntries must be non-zero.
 * The logRecordNamePtr "name" is reserved to the Name Registry. Don't use it.
 *
 * This function must be called in a context that can allocate memory. The first call
 * from a 68000 architecture module must be able to access the Code Fragment Manager.
 *
 * Return the LogRecordPtr for this log, or NULL if unsuccessful.
 */
pascal LogRecordPtr            MakeLogRecord(
        const LogRecordNamePtr    logRecordNamePtr,        /* Log name (C-string)        */
        UInt32                    nEntries                /* Number of Log entries    */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * GetLogRecordPtr
 *
 * Return a pointer to the log record for a specified name. Returns NULL if it was
 * not found (WriteLogEntry, etc. will not choke). The first call from a 68000
 * module must be able to access the Code Fragment Manager.
 */
pascal LogRecordPtr            GetLogRecordPtr(
        const LogRecordNamePtr    logRecordNamePtr        /* Log name (C-string)        */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * LogString
 *
 * LogString calls WriteLogEntry with a single Pascal string argument. Following ANSI
 * C conventions, it is provided as a macro and as a function. The function may be
 * called from Pascal.
 */
#define LogString(ptr, idCode, string) \
        WriteLogEntry((ptr), (idCode), LogStringFormat, string)
pascal OSErr                (LogString)(
        LogRecordPtr            logRecordPtr,            /* This log record            */
        OSType                    idCode,                    /* Entry identifier            */
        ConstStr255Param        string                    /* The datum                */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * LogStatusString
 *
 * LogStatusString calls WriteLogEntry with the status and string values. It is
 * provided as a macro and as a function.
 */
#define LogStatusString(ptr, idCode, status, string) (    \
        WriteLogEntry(                                    \
            (ptr),                                        \
            (idCode),                                    \
            LogStatusFormat,                            \
            (signed long) (status),                        \
            string                                        \
        )                                                \
    )
pascal OSErr                (LogStatusString)(
        LogRecordPtr            logRecordPtr,            /* This log record            */
        OSType                    idCode,                    /* Entry identifier            */
        OSErr                    status,                    /* Status error code        */
        ConstStr255Param        string                    /* The datum                */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * WriteLogEntry
 *
 * Write a LogRecord entry if logging is enabled and there is space in the log.
 *    logRecordPtr Identifies this log.
 *    idCode        A user-controlled value, by convention an OSType (4-byte character)
 *                that identifies this entry. The display application prints it. Note
 *                that, on the Macintosh, an OSType can be coerced from/to any longword
 *                scalar (such as an address) without loss of data. This may be useful
 *                for user-written display applications.
 *    format        A longword that specifies the format of the remaining data. Use the
 *                value LogStringFormat if the only datum is a Pascal string; use the
 *                value LogStatusFormat if you are logging an OSErr and an accompaning
 *                string; otherwise, use the LogFormat macro to create the value.
 *    ...            Additional data as needed. Note that all data must be specified as, or
 *                coerced to longwords (StringPtr, address, or long). Naturally short
 *                integers such as Booleans or OSErr codes must be explicitly cast to
 *                long. This is needed because of compiler options regarding data
 *                format lengths.
 * WriteLogData will always be in the current instruction architecture as you cannot
 * make a MixedMode call with a variable-length argument list. Also, WriteLogData
 * cannot be called from Pascal for the same reason.
 *
 * Return values:
 *    noErr        Normal completion or logging was disabled.
 *    writErr        The entry could not be stored because the LogRecord was full. This
 *                can usually be ignored.
 *    fBsyErr        The entry could not be stored because the LogRecord semaphore was
 *                locked -- presumably by an asynchronous process. The caller may
 *                wish to try the operation again, perhaps after a short delay.
 */
OSErr                        WriteLogEntry(
        LogRecordPtr            logRecordPtr,            /* This log record            */
        OSType                    idCode,                    /* Entry identifier            */
        UInt32                    format,                    /* Format bits                */
        ...                                                /* Additional data, if any    */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * StoreLogEntry
 *
 * Store a formatted LogEntryRecord in the log. This is the only routine that
 * writes the log entry. Normally, it is only called by WriteLogData. This function
 * will store the following data into the caller's LogEntryRecord (even if logging
 * was disabled or the log was full):
 *        sequence    This entry sequence counter.
 *        eventTime    UpTime when this record was added to the LogRecord.
 *
 * Return values:
 *    noErr        Normal completion or logging was disabled.
 *    writErr        The entry could not be stored because the LogRecord was full. This
 *                can usually be ignored.
 *    fBsyErr        The entry could not be stored because the LogRecord semaphore was
 *                locked -- presumably by an asynchronous process. The caller may
 *                wish to try the operation again, perhaps after a short delay.
 */
pascal OSErr                StoreLogEntry(
        LogRecordPtr            logRecordPtr,            /* This log record            */
        const LogEntryPtr        logEntryPtr                /* Gets this entry            */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * ReadLogEntry
 *
 * Read the next LogRecord entry. This returns a copy of the entry, if one is
 * available. ReadLogEntry also returns the UpTime value when it was called. This
 * is needed by 68000-based applications as the function is only available from the
 * Power PC native DriverServices library.
 *
 * Return values:
 *    noErr        Normal completion or logging was disabled.
 *    readErr        The entry could not be stored because the LogRecord was empty
 *    fBsyErr        The entry could not be stored because the LogRecord semaphore was
 *                locked -- presumably by an asynchronous process. The caller may
 *                wish to try the operation again, perhaps after a short delay.
 */
pascal OSErr                ReadLogEntry(
        LogRecordPtr            logRecordPtr,            /* This log record            */
        LogEntryPtr                thisLogEntry            /* Store entry here            */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * EnableLogRecord
 *
 * Enable/disable logging. Returns the old logging state.
 */
pascal Boolean32            EnableLogRecord(
        LogRecordPtr            logRecordPtr,            /* This log record            */
        Boolean32                enableLogging            /* TRUE to enable logging    */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * PreserveLogRecord
 *
 * Set the preserveFirst flag. Returns the old flag value.
 */
pascal Boolean32            PreserveLogRecord(
        LogRecordPtr            logRecordPtr,            /* This log record            */
        Boolean32                preserveFirst            /* TRUE to preserve start    */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * EnableLogUpTime
 *
 * Enable/disable recording of UpTime when WriteLogRecord. Returns the old state.
 * UpTime generally would be left in its original, enabled, state. The state may be
 * set FALSE to minimize the time needed to log data. If set FALSE, times will be
 * recorded as zero.
 */
pascal Boolean32            EnableLogUpTime(
        LogRecordPtr            logRecordPtr,            /* This log record            */
        Boolean32                enableUpTime            /* TRUE to enable UpTime    */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * GetLogSemaphoreLostCounter
 *
 * Because the log library uses a "lossy" algorithm to maintain exclusive access to
 * the critical section, there is a very slight possibility that two processes will
 * try to access the log record at the same time. In this case, ReadLogEntry will
 * stall (loop) and eventually succeed, while WriteLogEntry will lose the datum, and
 * increment the logLostCounter.
 */
pascal UInt32                GetLogSemaphoreLostCounter(
        LogRecordPtr            logRecordPtr            /* This log record            */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * FormatLogEntryData
 *
 * This function is in LogFormat.c - it formats an entry into a single line
 * that is stored in the result. Note: only the data is formatted: the timestamp
 * is not processed. This function may be called from a non-application context;
 * It does not require a MixedMode switch.
 */
pascal void                    FormatLogEntryData(
        const LogEntryPtr        thisLogEntry,            /* Format this entry        */
        StringPtr                result
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * LogConvertTimestamp
 *
 * This function is in LogConvertTimestamp.c - it formats the timestamp into civil
 * ("clock") time, returning the result in a DateTimeRec and an associated residual
 * number of nanoseconds. This routine calls Macintosh Toolbox services. It is not
 * in the shared library. Calling sequence:
 *        LogEntryRecord        thisLogEntry;
 *        UInt32                thisCivilTime;
 *        DateTimeRec            thisDateTime;
 *        UInt32                residualNanoseconds;
 *
 *        if (ReadLogEntry(myLogRecordPtr, &thisLogEntry)) {
 *            LogConvertTimestamp(
 *                &thisLogEntry,
 *                &thisDateTime,
 *                &residualNanoseconds
 *            );
 *        }
 * thisCivilTime will have the civil time (seconds since 1904) when the entry was
 * stored into the log. thisDateTime will have the corresponding civil date
 * (Year, Month, Day, Hour, Minute, Second)
 */
pascal void                    LogConvertTimestamp(
        const LogEntryPtr        logEntryPtr,            /* Current log entry        */
        DateTimeRec                *eventDateTime,            /* Year, Month, Day etc.    */
        UInt32                    *residualNanoseconds    /* Fractional second        */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * FormatLogEntryTimestamp
 *
 * Format a converted log entry timestamp (prepared by ConvertLogEntryTimestamp). The
 * result is appended to result as a fixed-length string: "yyyy.mm.dd hh.mm.ss.msec"
 * FormatLogEntryTimestamp does not use the system date formatting routines. Note
 * that the fractional seconds are truncated to the nearest lower millisecond, even
 * though nanosecond precision is potentially available. This function does not
 * require a MixedMode switch.
 */
pascal void                    FormatLogEntryTimestamp(
        StringPtr                result,                    /* Append to this string    */
        const DateTimeRec        *eventDateTime,            /* Year, Month, Day etc.    */
        UInt32                    residualNanoseconds        /* Fractional second        */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * LogRecord utilities.
 *
 * These three functions are used to locate all registered log records. They may be
 * used for a display utility or MacsBug dcmd. Applications call them as follows:
 *
 *    LogRecordIter            cookie;
 *
 *    if (LogRecordIterateCreate(&cookie) == noErr) {
 *        while ((logRecordPtr = LogRecordIterate(&cookie)) != NULL) {
 *            ... Process this LogRecord, the name may be extracted from the record ...
 *        }
 *        LogRecordIterateDispose(&cookie);
 *    }
 */
pascal OSErr                LogRecordIterateCreate(
        LogRecordIterPtr        cookie
    );
pascal LogRecordPtr            LogRecordIterate(
        LogRecordIterPtr        cookie
    );
pascal void                    LogRecordIterateDispose(
        LogRecordIterPtr        cookie
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * CopyLogRecord
 *
 * This function copies the permanent part of the LogRecord (srcLogRecordPtr) to a
 * caller-designated area (dstLogRecordPtr). It is only for the benefit of the DCMD.
 * It returns noErr if successful, paramErr if either the source or destination parameters
 * are incorrect, or a Shared Library Manager error. This function ignores the interlock
 * semaphore. Thus, it may return inconstent data. It does not copy the first LogRecordEntry.
 *
 * Only the DCMD is permitted to call this function!
 */
pascal OSErr                CopyLogRecordInfo(
        const LogRecordPtr        srcLogRecordPtr,
        LogRecordPtr            dstLogRecordPtr
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * CopyLogEntry
 *
 * Copy the specified LogRecord entry. This returns a copy of the entry. It is only
 * used by the DCMD to snapshot a LogRecord.
 *
 * Return values:
 *    noErr        Normal completion or logging was disabled.
 *    readErr        The entry could not be stored because the LogRecord was empty.
 *    fBsyErr        The entry could not be stored because the LogRecord semaphore was
 *                locked -- presumably by an asynchronous process. The caller may
 *                wish to try the operation again, perhaps after a short delay.
 */
pascal OSErr                CopyLogEntry(
        LogRecordPtr            logRecordPtr,            /* This log record            */
        UInt32                    getIndex,                /* This entry index            */
        LogEntryPtr                thisLogEntry            /* Store entry here            */
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * LogUpTime
 *
 * This is the DriverServicesLibrary UpTime function, callable from 68000. It is
 * called, once, by LogConvertTimestamp.
 *
 * Return values
 *    resultPtr    AbsoluteTime
 */
pascal void                    LogUpTime(
        AbsoluteTime            *resultPtr
    );
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * LogGetTimeBaseInfo
 *
 * This is the DriverServicesLibrary UpTime function, callable from 68000. It returns
 * only those values that LogConvertTimestamp needs.
 *
 * Return values
 *    upTimeNumerator        Needed for our AbsoluteToNanoseconds
 *    upTimeDenominator    Needed for our AbsoluteToNanoseconds
 */
pascal void                    LogGetTimeBaseInfo(
        UInt32                    *upTimeNumerator,
        UInt32                    *upTimeDenominator
    );

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * LogInitializeSharedLibraries
 *
 * This is called by the dcmd to bind the 68000 library to the Name Registry library.
 * It is only needed by LogLibrary68.c and must be called in an "application" context
 * as it allocates memory and accesses the file system.
 */
pascal void                    LogInitializeSharedLibraries(void);

#endif    /* __LogLibrary__    */